/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.googlecode.j4sc.service;

import java.io.IOException;

import com.googlecode.j4sc.conversion.Conversion;
import com.googlecode.j4sc.submission.Submission;
import com.googlecode.j4sc.submission.SubmissionReference;

/**
 * Interface to be implemented by a Service
 * 
 * @author Raj Patel, Dariusz Lorenc
 */
public interface IService {

    /**
     * Submit a {@link Submission} to the service for conversion
     * 
     * @param submission
     *            the submission
     * @return the {@link SubmissionReference} to be used when retrieving the
     *         conversion later using the {@link #retrieve(SubmissionReference)}
     *         method
     * @throws ServiceException
     *             thrown if the service responds with an error
     * @throws IOException
     *             thrown on I/O errors
     */
    public abstract SubmissionReference submit(Submission submission) throws ServiceException, IOException;

    /**
     * Retrieve a {@link Conversion} from this Service using the
     * {@link SubmissionReference}
     * 
     * @param reference
     *            the {@link SubmissionReference} as returned from
     *            {@link Service#submit(Submission)} method
     * @return the Conversion
     * @throws ServiceException
     *             thrown if the service responds with an error
     * @throws IOException
     *             thrown on I/O errors
     */
    public abstract Conversion retrieve(SubmissionReference reference) throws ServiceException, IOException;

}